一、概述

向量 類別繼承自原生 JavaScript 的 Array，用於表示一個數學上的向量。它支援所有標準的 Array 方法，並額外擴展了向量專用的數學運算和操作，使其適用於科學計算、數據分析等場景。

new 向量([初始值])

建立一個新的 向量 實例。

參數

初始值 (Array | number): (可選) 向量的初始值。預設為 0。
- 若為數字，將建立一個指定長度的向量，並以 0 填充。
- 若為陣列，將使用該陣列的元素來初始化向量。
- 若傳入多個參數，無論是數字或陣列，都會被展開並合併成單一向量。

拋出錯誤

參數錯誤: 當提供的初始值為負數時拋出。

範例

// 使用數字初始化一個長度為 5 的向量
const v1 = new 向量(5);
console.log(v1); // [0, 0, 0, 0, 0]

// 使用陣列初始化一個向量
const v2 = new 向量([1, 2, 3]);
console.log(v2); // [1, 2, 3]

// 使用內嵌的單元素陣列初始化
const v3 = new 向量([[42]]);
console.log(v3); // [42]

// 傳入負數將拋出錯誤
try {
  const v4 = new 向量(-1);
} catch (error) {
  console.error(error); // 參數錯誤: 長度必須大於等於零
}

二、屬性

範數 (norm)

計算並返回向量的歐幾里得範數（或稱長度、模長）。其計算方式為各元素平方和的平方根。

類型: number
唯讀: 是

範例

const v = new 向量(3, 4);
console.log(v.範數); // 輸出: 5 (因為 Math.sqrt(3^2 + 4^2) = 5)

三、方法

加(source)

將當前向量與另一個向量或一個純量（數字）相加。

參數

來源 (向量 | number | null | undefined): 用於加法的來源。
- 若為向量，則執行逐元素的加法。兩個向量的維度（長度）必須相同。
- 若為數字，則將向量的每個元素都加上此數字。
- 若為 null 或 undefined，則返回當前向量的一個複製。

(向量): 一個新的 向量 實例，為運算後的結果。

拋出錯誤

參數錯誤: 當來源是向量但其長度與當前向量不同時。

範例

const v1 = new 向量(1, 2, 3);
const v2 = new 向量(4, 5, 6);

// 向量與向量相加
const result1 = v1.加(v2);
console.log(result1); // 輸出: [5, 7, 9]

// 向量與純量相加
const result2 = v1.加(10);
console.log(result2); // 輸出: [11, 12, 13]

加總([排除項目])

計算向量中所有元素的總和，可選擇性地排除某些元素。

參數

排除項目 (位元陣列 | null): (可選) 一個 位元陣列 實例，標記哪些索引的元素不應被計入總和。若索引對應的值為 true，則該元素被排除。預設為 null，即計算所有元素的總和。

(number | undefined): 計算出的總和。如果向量為空或所有元素都被排除，則返回 undefined。

拋出錯誤

型別錯誤: 當 排除項目 不是 位元陣列 或 null 時。

範例

const v = new 向量(1, 2, 3, 4, 5);
const exclusions = new 位元陣列([false, true, false, true, false]); // 排除索引 1 (值2) 和 3 (值4)

const total = v.加總(exclusions);
console.log(total); // 輸出: 9 (1 + 3 + 5)

const fullTotal = v.加總();
console.log(fullTotal); // 輸出: 15

乘(倍數)

將向量中的每個元素乘以一個指定的倍數（純量）。

參數

倍數 (number): 要乘以的數值。

(向量): 一個新的 向量 實例，為純量乘法後的結果。

拋出錯誤

型別錯誤: 當 倍數 不是一個數字時。

範例

const v = new 向量(1, 2, 3);
const scaledVector = v.乘(3);
console.log(scaledVector); // 輸出: [3, 6, 9]

內積(另一個向量)

計算當前向量與另一個向量的內積（點積）。

參數

另一個向量 (向量): 用於計算內積的另一個向量。其長度必須與當前向量相同。

(number): 兩個向量的內積結果。

拋出錯誤

參數錯誤: 當兩個向量的維度（長度）不同時。

範例

const v1 = new 向量(1, 2, 3);
const v2 = new 向量(4, 5, 6);
const dotProduct = v1.內積(v2);
console.log(dotProduct); // 輸出: 32 (1*4 + 2*5 + 3*6)

外積(另一個向量)

計算當前向量與另一個向量的外積（叉積）。此運算僅適用於三維向量。

參數

另一個向量 (向量 | Array): 一個三維向量，用於計算外積。

(向量): 一個新的三維 向量，為外積的結果。

拋出錯誤

Error: 當任一向量不是三維時。

範例

const v1 = new 向量(1, 0, 0); // X 軸單位向量
const v2 = new 向量(0, 1, 0); // Y 軸單位向量
const crossProduct = v1.外積(v2);
console.log(crossProduct); // 輸出: [0, 0, 1] (Z 軸單位向量)

交換(a, b)

交換向量中兩個指定索引位置的元素。此方法會直接修改原始向量。

參數

a (number): 第一個元素的索引。
b (number): 第二個元素的索引。

(向量): 返回修改後的當前向量實例。

拋出錯誤

Error: 當任一索引超出向量的有效範圍時。

範例

const v = new 向量(10, 20, 30, 40);
v.交換(0, 3);
console.log(v); // 輸出: [40, 20, 30, 10]

等於(另一個向量)

判斷當前向量是否與另一個向量或陣列相等。相等定義為長度相同且所有對應位置的元素都相等（數值比較時允許極小的誤差，精度為 0.00000001）。

參數

另一個向量 (向量 | Array): 用於比較的另一個向量或陣列。

(boolean): 如果兩個向量相等，則返回 true，否則返回 false。

拋出錯誤

型別錯誤: 當傳入的參數不是 向量 或 陣列 時。

範例

const v1 = new 向量(1, 2, 3);
const v2 = new 向量(1, 2, 3);
const v3 = new 向量(1, 2, 4);
const arr = [1, 2, 3];

console.log(v1.等於(v2)); // 輸出: true
console.log(v1.等於(v3)); // 輸出: false
console.log(v1.等於(arr)); // 輸出: true

是零向量()

檢查當前向量是否為零向量（所有元素均為零）。

(boolean): 如果是零向量，返回 true，否則返回 false。

範例

const zeroVector = new 向量(0, 0, 0);
const nonZeroVector = new 向量(0, 1, 0);

console.log(zeroVector.是零向量()); // 輸出: true
console.log(nonZeroVector.是零向量()); // 輸出: false

有相鄰的(a, b)

檢查向量中是否存在一對相鄰的元素，其值分別為 a 和 b。

參數

a (*): 第一個項目。
b (*): 緊隨第一個項目的第二個項目。

(boolean): 如果找到了這樣一對相鄰的元素，返回 true，否則返回 false。

範例

const v = new 向量(1, 2, 3, 4);
console.log(v.有相鄰的(2, 3)); // 輸出: true
console.log(v.有相鄰的(3, 2)); // 輸出: false

最大值([排除項目])

尋找並返回向量中的最大值及其索引。

參數

排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素不應被納入比較的 位元陣列。預設為 null。

({值: number, 索引: number}): 一個包含最大值 值 和其 索引 的物件。

範例

const v = new 向量(10, 50, 20, 50);
const result = v.最大值();
console.log(result); // 輸出: { 值: 50, 索引: 3 } (返回最後一個找到的最大值)

最小值([排除項目])

尋找並返回向量中的最小值及其索引。

參數

排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素不應被納入比較的 位元陣列。預設為 null。

({值: number, 索引: number}): 一個包含最小值 值 和其 索引 的物件。

範例

const v = new 向量(10, 5, 20, 5);
const result = v.最小值();
console.log(result); // 輸出: { 值: 5, 索引: 3 } (返回最後一個找到的最小值)

第一個大於(目標值, [排除項目])

尋找並返回向量中第一個大於指定目標值的元素及其索引。

參數

目標值 (number): 用於比較的數值。
排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素不應被納入比較的 位元陣列。預設為 null。

({值: number, 索引: number} | {值: null, 索引: -1}): 如果找到，返回包含該元素 值 和 索引 的物件；否則返回 { 值: null, 索引: -1 }。

範例

const v = new 向量(10, 20, 30, 40);
const result = v.第一個大於(25);
console.log(result); // 輸出: { 值: 30, 索引: 2 }

第一個小於(目標值, [排除項目])

尋找並返回向量中第一個小於指定目標值的元素及其索引。

參數

目標值 (number): 用於比較的數值。
排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素不應被納入比較的 位元陣列。預設為 null。

({值: number, 索引: number} | {值: null, 索引: -1}): 如果找到，返回包含該元素 值 和 索引 的物件；否則返回 { 值: null, 索引: -1 }。

範例

const v = new 向量(40, 30, 20, 10);
const result = v.第一個小於(25);
console.log(result); // 輸出: { 值: 20, 索引: 2 }

更新全部(回呼函式, [排除項目])

使用一個回呼函式來更新向量中的每一個元素。此方法會直接修改原始向量。

參數

回呼函式 (function): 用於處理每個元素的函式。它接收 (當前值, 索引) 兩個參數，並應返回新的元素值。
排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素不應被更新的 位元陣列。預設為 null。

(向量): 返回更新後的當前向量實例。

拋出錯誤

型別錯誤: 當 排除項目 不是 位元陣列 或 null 時。

範例

const v = new 向量(1, 2, 3, 4);
const exclusions = new 位元陣列([false, true, false, false]); // 排除索引 1

v.更新全部((value, index) => value * 10, exclusions);
console.log(v); // 輸出: [10, 2, 30, 40]

複製()

建立並返回當前向量的一個淺層複製。

(向量): 一個與當前向量具有相同元素的新 向量 實例。

範例

const originalVector = new 向量(1, 2, 3);
const copiedVector = originalVector.複製();

console.log(copiedVector); // 輸出: [1, 2, 3]
console.log(originalVector === copiedVector); // 輸出: false

迭代(回呼函式, [排除項目])

遍歷向量中的每一個元素，並對其執行一個回呼函式。

參數

回呼函式 (function): 為每個元素執行的函式，接收 (值, 索引) 兩個參數。
排除項目 (位元陣列 | null): (可選) 標記哪些索引的元素應被跳過的 位元陣列。預設為 null。

(向量): 返回當前向量實例，以支援鏈式調用。

拋出錯誤

型別錯誤: 當 回呼函式 不是函式，或 排除項目 的型別不正確時。

範例

const v = new 向量('a', 'b', 'c');
v.迭代((value, index) => {
  console.log(`索引 ${index} 的值是 ${value}`);
});
// 輸出:
// 索引 0 的值是 a
// 索引 1 的值是 b
// 索引 2 的值是 c

附加(…要附加的項目)

將一個或多個項目（可以是數值、陣列或其他向量）附加到當前向量的末尾，並返回一個新的向量。

參數

...要附加的項目 (*): 一個或多個要附加到向量末尾的項目。如果項目是陣列或向量，其元素將被逐一附加。

(向量): 一個包含所有原始項目和附加項目的新 向量 實例。

範例

const v1 = new 向量(1, 2);
const v2 = new 向量(5, 6);
const newVector = v1.附加(3, [4], v2);
console.log(newVector); // 輸出: [1, 2, 3, 4, 5, 6]